home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / NEWSOFT / AUGUST / FREENET1 / !FreeNet / Docs / SWIs < prev    next >
Text File  |  1995-11-12  |  27KB  |  702 lines
  1.           The Programmer Interface to the FreeNet TCP/IP Stack
  2.  
  3.                           (C) Tom Hughes 1995
  4.  
  5. 0. Copyright
  6.  
  7.   The FreeNet module and application and the tools and documentation
  8.   that go with them are all copyright. They are however released as
  9.   freeware subject to certain terms and conditions. These are described
  10.   in the file named 'Licence' which should have accompanied this
  11.   document.
  12.  
  13. 1. Overview
  14.  
  15.   The FreeNet TCP/IP Stack provides the same interface to the programmer
  16.   that the Acorn TCP/IP stack does, namely a BSD sockets interface
  17.   provided via SWI calls. There is also a library of AOF object files
  18.   available that provides a BSD sockets interface to these calls for use
  19.   by C programmers.
  20.  
  21.   There is a one to one mapping between the SWI calls provided by the
  22.   FreeNet stack, and the normal BSD socket calls. The arguments are
  23.   passed in order starting with register 0 and working up, with the
  24.   return value being passed back in R0.
  25.  
  26.   The only difference is that errors are signaled by returning a RISC OS
  27.   error in the normal way (with V set and R0 pointing to an error block)
  28.   instead of by returning a value of -1. The error number in the error
  29.   block will be a normal Unix error code however, and the C library
  30.   veneers convert these errors back into a -1 return code with errno
  31.   set.
  32.  
  33.   The mapping between BSD calls and SWI calls is decribed by the
  34.   following table:
  35.  
  36.          SWI Number    SWI Name                BSD Call
  37.  
  38.            &41200      Socket_Creat            socket()
  39.            &41201      Socket_Bind             bind()
  40.            &41202      Socket_Listen           listen()
  41.            &41203      Socket_Accept           accept()
  42.            &41204      Socket_Connect          connect()
  43.            &41205      Socket_Recv             recv()
  44.            &41206      Socket_Recvfrom         recvfrom()
  45.            &41207      Socket_Recvmsg          recvmsg()
  46.            &41208      Socket_Send             send()
  47.            &41209      Socket_Sendto           sendto()
  48.            &4120A      Socket_Sendmsg          sendmsg()
  49.            &4120B      Socket_Shutdown         shutdown()
  50.            &4120C      Socket_Setsockopt       setsockopt()
  51.            &4120D      Socket_Getsockopt       getsockopt()
  52.            &4120E      Socket_Getpeername      getpeername()
  53.            &4120F      Socket_Getsockname      getsockname()
  54.            &41210      Socket_Close            close()
  55.            &41211      Socket_Select           select()
  56.            &41212      Socket_Ioctl            ioctl()
  57.            &41213      Socket_Read             read()
  58.            &41214      Socket_Write            write()
  59.            &41215      Socket_Stat             stat()
  60.            &41216      Socket_Readv            readv()
  61.            &41217      Socket_Writev           writev()
  62.            &41218      Socket_Gettsize         FD_SETSIZE
  63.            &41219      Socket_Sendtosm         ?
  64.  
  65.   The remainder of this document details each of these SWIs in full,
  66.   describing the arguments and possible return values.
  67.  
  68. 2. Error Codes
  69.  
  70.   The errors returned by the Socket SWIs are normal RISC OS errors,
  71.   complete with suitable explanatory text. The error number will be a
  72.   Unix error code. These numbers (and the sybolic names associated with
  73.   them) are as follows:
  74.  
  75.        Name            Number    Explanation
  76.  
  77.        EBADF              9      Invalid socket descriptor given
  78.        EFAULT            14      Buffer is invalid or too small
  79.        EINVAL            22      Invalid argument
  80.        EWOULDBLOCK       35      Socket is marked non-blocking, and
  81.                                  this operation would normally block
  82.        EINPROGRESS       36      Operation now in progress
  83.        EALREADY          37      Operation already in progress
  84.        EMSGSIZE          40      Message too long
  85.        ENOPROTOOPT       42      Option not supported by protocol
  86.        EPROTONOSUPPORT   43      Protocol not supported
  87.        ESOCKTNOSUPPORT   44      Socket type not supported
  88.        EOPNOTSUPP        45      Operation not supported
  89.        EAFNOSUPPORT      47      Address family not supported
  90.        EADDRINUSE        48      Address already in use
  91.        ENETUNREACH       51      Network unreachable
  92.        ECONNRESET        54      Connection reset by peer
  93.        ENOBUFS           55      No buffer space available
  94.        EISCONN           56      Socket is already connected
  95.        ENOTCONN          57      Socket is not connected
  96.        ECONNREFUSED      61      Connection refused
  97.        EHOSTUNREACH      65      Host unreachable
  98.  
  99.   Throughout the rest of this document, the symbolic names referred to
  100.   above will be used when talking about specific errors.
  101.  
  102. 3. Other Symbolic Constants
  103.  
  104.   Various other constants are used as arguments to Socket SWIs, and these
  105.   are referred to in this document by the symbolic names used for them
  106.   in the BSD library code. Their values are as follows:
  107.  
  108.        Name            Value           Name            Value
  109.  
  110.        SOCK_STREAM       1             SO_DEBUG           &0001
  111.        SOCK_DGRAM        2             SO_ACCEPTCONN      &0002
  112.        SOCK_RAW          3             SO_REUSEADDR       &0004
  113.                                        SO_KEEPALIVE       &0008
  114.        PF_INET           2             SO_DONTROUTE       &0010
  115.                                        SO_BROADCAST       &0020
  116.        AF_INET           2             SO_LINGER          &0080
  117.                                        SO_OOBINLINE       &0100
  118.        MSG_OOB          &01            SO_SNDBUF          &1001
  119.        MSG_PEEK         &02            SO_RCVBUF          &1002
  120.        MSG_EOR          &08            SO_SNDLOWAT        &1003
  121.        MSG_TRUNC        &10            SO_RCVLOWAT        &1004
  122.        MSG_WAITALL      &40            SO_SNDTIMEO        &1005
  123.        MSG_DONTWAIT     &80            SO_RCVTIMEO        &1006
  124.                                        SO_ERROR           &1007
  125.        SOL_SOCKET      &FFFF           SO_TYPE            &1008
  126.                                        
  127.        IP_OPTIONS        1             SIOCSIFADDR      &8020690C
  128.        IP_HDRINCL        2             OSIOCGIFADDR     &C020690D
  129.        IP_TOS            3             SIOCGIFADDR      &C0206921
  130.        IP_TTL            4             SIOCSIFDSTADDR   &8020690E
  131.                                        OSIOCGIFDSTADDR  &C020690F
  132.        TCP_NODELAY       1             SIOCGIFDSTADDR   &C0206922
  133.        TCP_MAXSEG        2             SIOCSIFFLAGS     &80206910
  134.                                        SIOCGIFFLAGS     &C0206911
  135.        FIOASYNC      &8004667D         OSIOCGIFBRDADDR  &C0206912
  136.        FIONBIO       &8004667E         SIOCGIFBRDADDR   &C0206923
  137.        FIONREAD      &4004667F         SIOCSIFBRDADDR   &80206913
  138.                                        OSIOCGIFCONF     &C0206914
  139.        SIOCATMARK    &80047307         SIOCGIFCONF      &C0206924
  140.                                        OSIOCGIFNETMASK  &C0206915
  141.                                        SIOCGIFNETMASK   &C0206925
  142.                                        SIOCSIFNETMASK   &80206916
  143.                                        SIOCGIFMETRIC    &C0206917
  144.                                        SIOCSIFMETRIC    &80206918
  145.                                        SIOCDIFADDR      &80206919
  146.                                        SIOCAIFADDR      &80206920
  147.  
  148. 4. Socket_Creat
  149.  
  150.   In: R0 = Protocol family
  151.       R1 = Socket type
  152.       R2 = Protocol
  153.  
  154.   Out: R0 = Socket descriptor
  155.  
  156.   This call creates a new socket of a given type and using a given
  157.   protocol.  If the protocol is left unspecified (passed as zero), a
  158.   default applicable to that socket type will be used.
  159.  
  160.   The internet protocol family (PF_INET) is the only one supported by this
  161.   module. Three socket type are supported:
  162.  
  163.     SOCK_STREAM - Stream orientated connections providing bi-directional
  164.                   sequenced, reliable transfer of byte streams. The only
  165.                   protocol of this type currently supported is the
  166.                   transmission control protocol (TCP).
  167.  
  168.     SOCK_DGRAM  - Connectionless, messages based protocols providing
  169.                   unreliable, non-sequence communication. The only
  170.                   protocol of this type currently supported is the user
  171.                   datagram protocol (UDP).
  172.  
  173.     SOCK_RAW    - Low level access to the underlying packet based
  174.                   transport mechanism to allow the implementation of
  175.                   alternative higher level protocols.
  176.  
  177.   Note that this call will not give the socket an address, or connect it
  178.   to any remote address. The socket can be given an address explicitly
  179.   using the Socket_Bind call, or it will be assigned one automatically
  180.   when it is first used to send data or to connect to a remote address.
  181.  
  182. 5. Socket_Bind
  183.  
  184.   In: R0 = Socket descriptor
  185.       R1 = Pointer to local address to bind socket to
  186.       R2 = Size of local address
  187.  
  188.   Out: R0 corrupted
  189.  
  190.   This call binds a socket to a specified local address. The format of
  191.   the address (for Internet addresses) is:
  192.  
  193.     R1 + 0 = Address family
  194.          2 = Port number
  195.          4 = IP address
  196.          8 = Reserved (should be zero)
  197.  
  198.   The address family is always AF_INET for internet addresses. The
  199.   reserved portion of the address can be omitted, provided that the
  200.   address size is passed correctly to indicate this.
  201.  
  202.   Note that the port number and IP address need to be in network byte
  203.   order, which is the reverse of the normal byte order on all current
  204.   Acorn machines.
  205.  
  206. 6. Socket_Listen
  207.  
  208.   In: R0 = Socket descriptor
  209.       R1 = Maximum backlog
  210.  
  211.   Out: R0 corrupted
  212.  
  213.   This call causes a socket of type SOCK_STREAM to begin listening for
  214.   incoming connection attempts. The backlog parameter specifies the
  215.   maximum length that the queue of pending connections may grow to
  216.   before connection attempts will be refused.
  217.  
  218. 7. Socket_Accept
  219.  
  220.   In: R0 = Socket descriptor of listening socket
  221.       R1 = Pointer to address to be filled in
  222.       R2 = Pointer to word giving the size of the address block
  223.  
  224.   Out: R0 = Socket descriptor for new connection
  225.  
  226.   This call is used to accept connections from server sockets that have
  227.   been told to listen for new connections. A new socket will be created
  228.   for each incoming connection, and this call in then used to obtain the
  229.   descriptor for the next pending connection.
  230.  
  231.   The address of the host which initiated the returned connection will
  232.   also be returned, in the supplied address block. This block is in the
  233.   same format as that given to Socket_Bind.
  234.  
  235.   If there are no connections waiting to be accepted, this call will
  236.   block until a connection is available to be returned, unless the
  237.   socket has been marked as non-blocking using Socket_Ioctl, in which
  238.   case the error EWOULDBLOCK will be returned.
  239.  
  240. 8. Socket_Connect
  241.  
  242.   In: R0 = Socket descriptor
  243.       R1 = Pointer to address of remote host
  244.       R2 = Size of supplied address block
  245.  
  246.   Out: R0 corrupted
  247.  
  248.   This call initiates a connection from the specified socket to a given
  249.   address on another host. When used on a raw or datagram socket, this
  250.   will simply fix the remote address for future calls to Socket_Send,
  251.   and this remote address can be changed by calling this routine again.
  252.  
  253.   For stream sockets, FreeNet will attempt to make a connection to the
  254.   specified address, and will block until the connection is achieved or
  255.   the attempt fails. If the socket has been marked non-blocking it will
  256.   instead return immediately with the error EINPROGRESS and will continue
  257.   with the connection attempt on its own.
  258.  
  259. 9. Socket_Recv
  260.  
  261.   In: R0 = Socket descriptor
  262.       R1 = Pointer to buffer for received data
  263.       R2 = Size of buffer
  264.       R3 = Flags
  265.  
  266.   Out: R0 = Amount of data received
  267.  
  268.   This call reads as much data as possible from the specified socket, and
  269.   returns it in the supplied buffer. If no data is available, the call
  270.   will block until data is available, unless the socket has been marked
  271.   non-blocking, in which case EWOULDBLOCK will be returned.
  272.  
  273.   Various bits in the flags word can be set to affect how how the read
  274.   is performed:
  275.  
  276.     MSG_PEEK     - Just peek at the data, leaving it in place to be
  277.                       read by a subsequent call.
  278.  
  279.     MSG_OOB      - Read any out-of-band data that is waiting on the
  280.                       socket, in place of the normal data.
  281.  
  282.     MSG_DONTWAIT - Treat this particular call as non-blocking, ignoring
  283.                    the sockets normal blocking/non-blocking status.
  284.  
  285.     MSG_WAITALL  - Try and completely fill the supplied buffer, blocking
  286.                    for more data if necessary.
  287.  
  288.   For stream sockets, this call may return zero as an indication that the
  289.   other end has closed the connection.
  290.  
  291. 10. Socket_Recvfrom
  292.  
  293.   In: R0 = Socket descriptor
  294.       R1 = Pointer to buffer for received data
  295.       R2 = Size of buffer
  296.       R3 = Flags
  297.       R4 = Pointer to address to be filled in
  298.       R5 = Size of supplied address block
  299.  
  300.   Out: R0 = Amount of data received
  301.  
  302.   This call has identical functionality to Socket_Recv except that the
  303.   address of the host that sent the data will be returned in the block
  304.   supplied, in the same format as used by Socket_Bind.
  305.  
  306. 11. Socket_Recvmsg
  307.  
  308.   In: R0 = Socket descriptor
  309.       R1 = Pointer to message descriptor
  310.       R2 = Flags
  311.  
  312.   Out: R0 = Amount of data received
  313.  
  314.   This call behaves in the same way as Socket_Recvfrom, except that the
  315.   message descriptor is used to indicate where the address should be
  316.   placed and to give a list of buffers to return the data in. The format
  317.   of the message descriptor is:
  318.  
  319.     R1 + 0  = Pointer to address to be filled in
  320.        + 4  = Size of supplied address block
  321.        + 8  = Pointer to array of buffer descriptors
  322.        + 12 = Number of buffer descriptors in use
  323.        + 16 = Pointer to list of access rights (unused by FreeNet)
  324.        + 20 = Size of access rights list
  325.        + 24 = Flags for received data
  326.  
  327.   Each buffer descriptor consists of two words. The first is a pointer
  328.   to the buffer, and the second the size of the buffer. The flags which
  329.   can be returned in the message descriptor are:
  330.   
  331.     MSG_TRUNC - Message was truncated.
  332.     
  333.     MSG_EOR   - This data completes a record.
  334.  
  335. 12. Socket_Send
  336.  
  337.   In: R0 = Socket descriptor
  338.       R1 = Pointer to data to be sent
  339.       R2 = Size of buffer
  340.       R3 = Flags
  341.  
  342.   Out: R0 = Amount of data sent
  343.  
  344.   This call sends data on a socket. In the case of datagram and raw sockets,
  345.   a single datagram containing the data will be sent, and EMSGSIZE will be
  346.   returned if the data is too large to be sent in this way. For stream
  347.   sockets, the call will block until all the data has been sent, unless
  348.   the socket has been marked non-blocking, in which case as much data as
  349.   possible will be sent.
  350.  
  351.   Various bits in the flags word can be set to affect how how the send is
  352.   performed:
  353.  
  354.     MSG_OOB      - Send data as out-of-band data instead of normal
  355.                     in-band data.
  356.  
  357.   Because this call does not specify the address to send to, the socket
  358.   used for this call must be a connected socket.
  359.  
  360. 13. Socket_Sendto
  361.  
  362.   In: R0 = Socket descriptor
  363.       R1 = Pointer to data to be sent
  364.       R2 = Size of buffer
  365.       R3 = Flags
  366.       R4 = Pointer to address to send to
  367.       R5 = Size of supplied address block
  368.  
  369.   Out: R0 = Amount of data sent
  370.  
  371.   This call performs the same job as Socket_Send, except that the remote
  372.   address is specified so that it can be used on unconnected sockets. This
  373.   call is only useful for sockets that do not require a connection such
  374.   as those using the UDP protocol. For sockets that require a connection
  375.   such as those using the TCP protocol, you need to call Socket_Connect
  376.   before you can use this routine, and the address given to this call
  377.   is then ignored anyway.
  378.  
  379. 14. Socket_Sendmsg
  380.  
  381.   In: R0 = Socket descriptor
  382.       R1 = Pointer to message descriptor
  383.       R2 = Flags
  384.  
  385.   Out: R0 = Amount of data sent
  386.  
  387.   This call behaves in the same way as Socket_Sendto, except that the
  388.   message descriptor is used to indicate where the address should be
  389.   taken from and to give a list of buffers containing the data in. The
  390.   format of the message descriptor is as given for Socket_Recvmsg.
  391.  
  392. 15. Socket_Shutdown
  393.  
  394.   In: R0 = Socket descriptor
  395.       R1 = Direction of shutdown
  396.  
  397.   Out: R0 corrupted
  398.  
  399.   Perform a half close on a stream socket. This call is able to shut
  400.   down either the send or received side of the socket, or both. The
  401.   direction parameter is either 0 to shut down the receive side, 1 to
  402.   shut down the send side, or 2 to shut down both sides of the socket.
  403.  
  404. 16. Socket_Setsockopt
  405.  
  406.   In: R0 = Socket descriptor
  407.       R1 = Option level
  408.       R2 = Option
  409.       R3 = Pointer to option value
  410.       R4 = Size of option value
  411.  
  412.   Out: R0 corrupted
  413.  
  414.   This is used to set a particular option on a socket. The level is
  415.   either SOL_SOCKET for options applicable to all sockets, or a protocol
  416.   number for options applicable to a certain protocol. Currently
  417.   supported socket level options are:
  418.  
  419.     SO_REUSEADDR - Enables or disables the reuse of local addresses
  420.                    during the wait period that normally occurs when
  421.                    a TCP stream socket is closed. The argument is a
  422.                    single word which contains zero to disable this
  423.                    option, or a non-zero value to enable it.
  424.  
  425.     SO_KEEPALIVE - Enable or disable attempts by FreeNet to probe the
  426.                    remote end of a TCP connection when the link has
  427.                    been idle for some time.
  428.  
  429.     SO_BROADCAST - Enable or disable sending of broadcast packets
  430.                    through this socket.
  431.  
  432.     SO_LINGER    - Control whether the socket lingers on close. The
  433.                    argument points to two words, the first of which
  434.                    is a boolean that indicates wether the socket waits
  435.                    for data to drain when it is closed, and the
  436.                    second is the length of time to wait in seconds.
  437.  
  438.     SO_OOBINLINE - Control whether OOB data is received inline with
  439.                    the normal data, or out of line as a separate data
  440.                    stream.
  441.  
  442.     SO_SNDBUF    - Set the size of the send buffer to the value given
  443.                    by the argument, which is a single word.
  444.  
  445.     SO_RCVBUF    - Set the size of the receive buffer to the value given
  446.                    by the argument, which is a single word.
  447.  
  448.     SO_SNDLOWAT  - Set the low water mark of the send buffer. The stack
  449.                    will block a send until there is this much space in
  450.                    the send buffer before it starts to send the data.
  451.  
  452.     SO_RCVLOWAT  - Set the low water mark of the receive buffer. The
  453.                    stack will always try and return at least this many
  454.                    bytes on a read, blocking if necessary.
  455.  
  456.     SO_SNDTIMEO  - Set the send timeout. This is the maximum length
  457.                    of time that a send call will block for before
  458.                    returning. The argument is a pointer to a timeout
  459.                    block as described under Socket_Select.
  460.  
  461.     SO_RCVTIMEO  - Set the receive timeout. This is the maximum length
  462.                    of time that a receive call will block for before
  463.                    returning. The argument is a pointer to a timeout
  464.                    block as described under Socket_Select.
  465.  
  466.   The IP protocol also supports several options:
  467.  
  468.     IP_OPTIONS   - Set some IP options which will be added to each
  469.                    packet sent on a socket.
  470.  
  471.     IP_HDRINCL   - This toggles whether data sent on a socket already
  472.                    has an IP header included or not. This should only
  473.                    ever be set on raw sockets.
  474.  
  475.     IP_TOS       - Set the type of service field in packets sent using
  476.                    this socket to the specified value.
  477.  
  478.     IP_TTL       - Set the time to live field in packets sent using
  479.                    this socket to the specified value.
  480.  
  481.   Finally, there are a number of options supported by the TCP protocol:
  482.  
  483.     TCP_NODELAY - Disable the Nagle algorithm for this connection, to
  484.                   ensure that data is always sent immediately.
  485.  
  486.     TCP_MAXSEG  - Set the maximum segment size to use for data sent on
  487.                   this connection.
  488.  
  489. 16. Socket_Getsockopt
  490.  
  491.   In: R0 = Socket descriptor
  492.       R1 = Option level
  493.       R2 = Option
  494.       R3 = Pointer to buffer for option value
  495.       R4 = Size of option value buffer
  496.  
  497.   Out: R0 corrupted
  498.  
  499.   This call can be used to read the current value of any of the options
  500.   set using Socket_Setsockopt. In addition, there are two more socket
  501.   level options that can be read but not written:
  502.  
  503.     SO_ERROR - Return the Unix error code for any error which has
  504.                occurred on the socket, and clear the sockets error
  505.                flag.
  506.  
  507.     SO_TYPE  - Return the socket type set when the socket was
  508.                created.
  509.  
  510. 17. Socket_Getpeername
  511.  
  512.   In: R0 = Socket descriptor
  513.       R1 = Pointer to address to be filled in
  514.       R2 = Pointer to word giving the size of the address block
  515.  
  516.   Out: R0 corrupted
  517.  
  518.   This call returns the address that the socket is connected to (if any)
  519.   in the supplied address block.
  520.  
  521. 18. Socket_Getsockname
  522.  
  523.   In: R0 = Socket descriptor
  524.       R1 = Pointer to address to be filled in
  525.       R2 = Pointer to word giving the size of the address block
  526.  
  527.   Out: R0 corrupted
  528.  
  529.   This call returns the local address that the socket is bound to (if
  530.   any) in the supplied address block.
  531.  
  532. 19. Socket_Close
  533.  
  534.   In: R0 = Socket descriptor
  535.   
  536.   Out: R0 corrupted
  537.  
  538.   Close a socket, freeing the descriptor for reuse. For stream sockets,
  539.   this is roughly equivalent to calling Socket_Shutdown with a type code
  540.   of 2, whilst for datagram sockets this call immediately deletes the
  541.   socket.
  542.  
  543. 20. Socket_Select
  544.  
  545.   In: R0 = Number of descriptors to consider in each set
  546.       R1 = Pointer to read descriptor set
  547.       R2 = Pointer to write descriptor set
  548.       R3 = Pointer to exception descriptor set
  549.       R4 = Pointer to timeout block
  550.  
  551.   Out: Number of ready descriptors
  552.  
  553.   This call polls a specified groups of sockets to see which are ready
  554.   for reading, which are ready for writing and which had exceptional
  555.   conditions pending.
  556.  
  557.   Each of the three descriptor sets is a bitmask, where bit zero refers
  558.   to socket zero, bit one to socket one and so on. Only those sockets
  559.   whose bit is set in a mask will be considered when performing the
  560.   checks. As FreeNet currently supports 128 sockets, the bitmasks are
  561.   arrays of four words - descriptors 0 to 31 are in the first word and
  562.   so on.
  563.  
  564.   The value in R0 is the number of bits in the descriptor sets which
  565.   should be considered as having meaning, so if R0 is 9 only the
  566.   first 9 bits (descriptors 0 to 8) will be considered.
  567.  
  568.   This call will return as soon as one or more of the sockets being
  569.   tested is ready or when a timeout occurs. Passing a null pointer
  570.   for the timeout means the call will never timeout, and will block
  571.   until a socket is ready. The timeout takes the following form:
  572.  
  573.     R4 + 0 = Number of seconds to wait
  574.          4 = Number of microseconds to wait
  575.  
  576.   A timeout with both fields set to zero will cause the call to return
  577.   immediately, regardless of how many sockets are ready.
  578.  
  579. 21. Socket_Ioctl
  580.  
  581.   In: R0 = Socket descriptor
  582.       R1 = Operation
  583.       R2 = Pointer to argument
  584.  
  585.   Out: R0 corrupted
  586.  
  587.   This call is used to perform miscellaneous control operations on
  588.   individual sockets and on the TCP/IP stack as a whole. At the moment,
  589.   these operations are supported:
  590.  
  591.     FIOASYNC   - Mark a socket for asynchronous operation. This means that
  592.                  a RISC OS event will be raised when important changes
  593.                  occur in the sockets status. See the section on events
  594.                  for more detail of the events that are raised. The argument
  595.                  is a single word acting as a boolean flag.
  596.  
  597.     FIONBIO    - Mark a socket non-blocking so that no attempted operations
  598.                  on the socket will block. They will instead fail with the
  599.                  error EWOULDBLOCK if they are unable to complete straight
  600.                  away. The argument is a single word acting as a boolean
  601.                  flag.
  602.  
  603.     FIONREAD   - Read the number of bytes available for reading from the
  604.                  socket. The argument is an integer which will be filled in
  605.                  with the number of bytes available.
  606.  
  607.     SIOCATMARK - Read a boolean indicator that says whether we are at
  608.                  the OOB marker in the data stream.
  609.  
  610.   This call also supports certain operations on the interface table, but
  611.   details of this are outside the current scope of this document. Future
  612.   extensions will implement the remaining operations on the routing table
  613.   and also a set of operations on the routing tables.
  614.  
  615. 22. Socket_Read
  616.  
  617.   In: R0 = Socket descriptor
  618.       R1 = Pointer to buffer for received data
  619.       R2 = Size of buffer
  620.  
  621.   Out: R0 = Amount of data received
  622.  
  623.   This call reads data from a socket in the same style as Socket_Recv
  624.   except that there is no flags argument, so all flags are treated as
  625.   being zero.
  626.  
  627. 23. Socket_Write
  628.  
  629.   In: R0 = Socket descriptor
  630.       R1 = Pointer to data to be sent
  631.       R2 = Size of buffer
  632.  
  633.   Out: R0 = Amount of data sent
  634.  
  635.   This call sends data on a socket in the same style as Socket_Send
  636.   except that there is no flags argument, so all flags are treated as
  637.   being zero.
  638.  
  639. 24. Socket_Stat
  640.  
  641.   This call is not supported by FreeNet yet.
  642.  
  643. 25. Socket_Readv
  644.  
  645.   In: R0 = Socket descriptor
  646.       R1 = Pointer to array of buffer descriptors
  647.       R2 = Number of buffer descriptors
  648.  
  649.   Out: R0 = Amount of data received
  650.  
  651.   This call reads data into a gather array. The buffer descriptors are
  652.   the same as those described for Socket_Recvmsg, and as with Socket_Read
  653.   the flags are all treated as being zero.
  654.  
  655. 25. Socket_Writev
  656.  
  657.   In: R0 = Socket descriptor
  658.       R1 = Pointer to array of buffer descriptors
  659.       R2 = Number of buffer descriptors
  660.  
  661.   Out: R0 = Amount of data received
  662.  
  663.   This call sends data from a scatter array. The buffer descriptors are
  664.   the same as those described for Socket_Recvmsg, and as with Socket_Write
  665.   the flags are all treated as being zero.
  666.  
  667. 26. Socket_Gettsize
  668.  
  669.   In: Nothing
  670.  
  671.   Out: R0 = Number of descriptors available
  672.  
  673.   This call returns the number of descriptors available to the caller,
  674.   including those currently in use.
  675.  
  676. 27. Socket_Sendtosm
  677.  
  678.   This call is not supported by FreeNet yet.
  679.  
  680. 28. The Internet Event
  681.  
  682.   If a socket has been marked for asynchronous operation using Socket_Ioctl
  683.   the TCP/IP stack will raise a RISC OS event (event 19) when important
  684.   changes occur which affect the socket. When the event occurs, registers
  685.   will be set as follows:
  686.  
  687.      R0 = 19
  688.      R1 = Event code
  689.      R2 = Socket descriptor
  690.  
  691.   Where the socket descriptor is the socket affected by the event, and the
  692.   event code is on of the following values:
  693.  
  694.      1   Socket has input waiting to be read
  695.      2   An urgent event has occured (eg arrival of OOB data )
  696.      3   Socket's connection has been broken
  697.  
  698.   This event can be trapped and used to know when to read data from the
  699.   socket, and when a connection has been closed.
  700.  
  701. $Id: SWIs,v 1.1.2.1 1995/11/12 17:44:07 tom Exp $
  702.